SPACE 1

home *** CD-ROM | disk | FTP | other *** search

/ SPACE 1 / SPACE - Library 1 - Volume 1.iso / misc~1 / 123 / stcitdoc.arc / NETHACK.DOC < prev next >

Wrap

Text File | 1987-11-08 | 12.6 KB | 318 lines

NETHACK.DOC Once over lightly This section provides a Utopian view of the Citadel auto networking protocol -- it ignores possible foulup points, and generally assumes that the gremlins of the world don't exist, and are gonadless in any case. Irrelevant complexities and gremlins are covered in following sections. FLOW DIAGRAM ----------------- | CALL | | STABILIZATION | ----------------- RECEIVER TELLS CALLER CAN'T HANDLE COMMAND | +-------------------<-----+ | | | ---------------- ---------------- ------------ ^ | CALLER SENDS |->---| CALLER SENDS |--->--| RECEIVER |--->| | ID & NAME | | COMMAND | | RESPONDS | | ---------------- ---------------- ------------ V | | | | | -------------- | | RECEIVER | | | TELLS | ^ | CALLER | | | CAN HANDLE | | | COMMAND | | -------------- | | | | | UNLESS COMMAND IS ---------------- +------------<----------| DO SPECIFIED | 'HANGUP' | ACTION | ---------------- The key is in having a reliable WC protocol available, because all commands are sent via WC protocol. -------------------------------------------------------------------- CALL STABILIZATION The purpose of this process is to establish quickly and efficiently that the caller is another system on the net that wishes to give the receiver some info. Here is the process (sort of) graphically: Caller | Receiver ------ | -------- Systems detect carrier Wait for full second | Wait for full second Send following 3 bytes: | Begin waiting for the 7 | following three bytes: 13 | 7 69 | 13 and wait 4 seconds. | 69 If have not received a | After the 4 second correct response (see | response wait, the Receiver Receiver column), then | can switch bauds if it resend the above 3 bytes. | is running in a SEARCHBAUD This looping process should | configuration. If get the only be repeated 20 times. | above 3 bytes, then respond If, on the 20th try, still | instantly with the following: have not received a correct | ~7 response, HANGUP. | ~13 If have received a correct | ~69 response, send an ACK. | and then wait for an ACK. | This should end CALL | STABILIZATION. So, essentially, the caller waits a second, and then sends a 3 byte sequence to the receiver. When the receiver receives those 3 bytes successfully, it replies with the logical negation of those 3 bytes. The caller then sends an ACK back, indicating that the call is stabilized. If 20 times the protocol fails, then the caller hangs up, assuming something was wrong. -------------------------------------------------------------------- CALLER SENDS NAME, ID, AND PASSWORD After receiving the ACK indicating end of CALL STABILIZATION, both will use Ward Christensen protocol for data exchange. Therefore, the next byte originates with the receiver, and that byte is the startup NAK. The caller sends, in this order, nodeid, nodename, and the password (if any) it needs to get access to the other system. nodeid, nodename, password: Are normal null-terminated C strings. So, for example, let's say that a system using the nodename "buffalo" and with a nodeId of "US 612 477 0927" called some other system. After the WC session was over, the receiver's buffer or temporary file would look like this Id name US 612 477 0927<0>Buffalo<0><0>[nulls] If WC fails at this point, the systems should hangup. If `Buffalo' is calling a system that needs the password `Gloopza', the receiver's buffer would look like this ID name password US 612 477 0927<0>Buffalo<0>Gloopza<0>[nulls] -------------------------------------------------------------------- COMMAND REQUESTS So, what happens next? It's a loop, in which the caller tells the receiver that he wants to do thus-and-so, the receiver responds with either "Fine, let's get on with it," or "Nope, [reason]". In more detail, it looks like this. First, remember that all communication is via WC protocol. A 'complete' command is a 1-byte command followed by 0 to 4 null terminated strings, followed by a null byte. Currently, the strings can only be 19 characters long. So, for instance, if we were to send only a single byte command, the sector received by the Receiver would look like this: <command-byte><0>[rest of sector, irrelevant] A command that also needs to send, say, two strings to the receiver would look like this: <command-byte><string1><string2><0>[rest of sector, irrelevant] Where string1 and string2 are null-terminated. These nulls (for the strings) should not* be mistaken for the end of command null! So, the receiver has received the command. At this point, the receiver must decide if he wants to (or can) execute the command requested by the caller. If he can, he just sends back (via WC) one byte, called GOOD, and then does what the command implies is next. If, for any number of reasons, he can't, he should then send back one byte, called BAD, and a null-terminated string (< 126 characters) that is simply text that tells the caller why he can't execute, e.g., facility not supported, this room doesn't exist, etc. If BAD is sent back, then the caller does the next thing on his list of things to do. At this point, the protocol is finished and the receiver should hangup. In the future, this may have more added on for generalizing networking. The actual values of BAD and GOOD: BAD: 0 GOOD: 1 -------------------------------------------------------------------- NET MESSAGE FORMAT The format for all messages on the net (currently only the net Mail) consists of a collection of C strings (text followed by a null) that represents all the data associated each message. Each field is identified by the first character of text in that field, and each identifier is unique. The fields may come in any order, with the exception that the Message text itself is the last field. Any data following the null byte that ends the Message field is assumed to be part of the next message, or the almost inevitable garbage that occurs in the last sector of a WC transfer. All data is straight ASCII, ended with a null byte, including those fields that could* be encoded in binary. The following fields and identifiers are currently supported. Identifier Data Max Length ---------- ---- ---------- 'A' Author of current message. 125 'D' Date on which message was written. 19 'N' Name of system which message was 19 written on. 'O' ID of system which message was written 19 on (i.e., "US 612 866 1804"). 'R' Room which message was originally 19 written in. 'S' Message ID on source system, in old 19 CP/M Citadel 8-bit style (i.e., 32 bit number split into two 16 bitters. See below in the example). 'T' Recipient of message (normally for 125 private Mail). 'C' Time message was written. 19 'M' Message text, all CRs changed to Line 9999 Feeds. 'Z' Network routing code, in the form 21 @<sigchar><message-id of routing system> So, a message on Test System (nodeId US 612 866 1804, nodeName 'C86 Test System') that looks like this: 86Feb01 @ 10:01 from John Flash in Other Citadels> This is a test. with a message ID of 5644 might look like this during transmission on the net: D86Feb01<0>C10:01<0>S0 5644<0>NC-86 Test System<0>OUS 612 8661804<0>AJohn <space>Flash<0>ROther Citadels<0>Z@LUS 612 8661804<0>MThis is a test<LF><0> Clear as mud, right? -------------------------------------------------------------------- CURRENTLY SUPPORTED FACILITIES So, what's available? The following. NORMAL_MAIL: This is simply a request for the receiver to accept for delivery to users on the receiver's system of mail from the caller. The command simply consists 1 byte -- no string parameters. If the receiver signals back that he can handle this facility (and he'd better, this is the first and most basic one of the network!), then the caller sends all Mail messages destined for the receiver to the receiver via WC protocol -- i.e., the receiver, after sending back the GOOD byte, goes into WC receive mode. The value of the command byte for NORMAL_MAIL is 1. ROOM_FILE_REQUEST: This is a request that the receiver send to the caller the file that is in the named room. The 'complete' command for this facility is the byte followed by two strings. The first string is the room where the file is (supposedly) located, the second string is the name of the file that the caller wants (this must be unambiguous). For example, if the user wanted the file named FOOBAR that resides in the room Neologisms, the command sequence (sent via WC) would look like this: <ROOM_FILE_REQUEST command byte>Neologisms<0>FOOBAR<0><0> The second <0> after FOOBAR indicates that FOOBAR is the last parameter for this command. The receiver then must evaluate what it has just read. Supposing that it supports file transfers, it must then determine if the room exists and if it is a directory room. If not, it would send back a BAD byte and a string indicating the problem. If the room is there and is directory, then it must query the directory to see if the requested file (FOOBAR). If it's not there, then, again, the receiver sends back a BAD byte and a string indicating the problem. If it is found, then the receiver sends back a GOOD byte (via WC) and then goes into WC send mode; the caller, upon receipt of the GOOD byte, goes into WC receive mode. The receiver then sends via WC the requested file. The value of the ROOM_FILE_REQUEST is 2. AMBIGUOUS_FILE_TRANSFERS: This is an expansion of the above facility, allowing the request of multiple files from a given Directory room. Data format for the request is the same as above, with the exception that the command byte's value will (of course) be different. The receiver then checks for the existence of the room, and whether or not it is a directory room. If either is false, then it replies BAD to the caller, along with a reason. If both are true, then the receiver replies GOOD. The files that match the given ambiguous file name (the match itself depends on the receiver's operating system) are now sent. Each file ("filename") that matches goes through the following sequential process. a) The receiver sends the filename and the size of the file (the size calculated in 128 byte sectors) through WC protocol. Both the file name and the size are C strings. For instance, if the file SEX.ED is to be sent, and is 12877 bytes long, the receiver would send to the caller the following data block: SEX.ED<0>101<0><rest of sector, irrelevant> Note that the size of the sectors is 101 rather than 100 -- the size is rounded up. b) After finishing the above data, the receiver then sends the file itself, also (of course) via WC. At the moment, the file size is not used for anything. However, it may prove useful in the future, since sending a file can be aborted by the caller by sending a CAN rather than a NAK. When the receiver has no more files to send, the file name "" (i.e., just a 0 byte rather than a file name) is sent. AMBIGUOUS_FILE_REQUEST command byte value is 3. In STadel, AMBIGUOUS_FILE_REQUEST is slowly obsoleting FILE_REQUEST, because a single file request is merely an ambiguous file request with an unambiguous name. HANGUP: This command is a simple 1-byte command that tells the receiver to hang up. Upon receipt, the receiver doesn't bother with replying to the caller -- he just hangs up. Obviously, the caller should have completed all other commands by now. The value of the HANGUP byte is 0. Other commands can (and will) be integrated into this structure with little difficulty.